{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# _Quantum Shift Registers using IBM Qiskit_\n",
    "\n",
    "Shift registers have been around for quite some time now. They play essential roles in digital circuits to manipulate the movement of data and _classicaly_ are represented as a cascade of flip flops. More importantly, they can be usde to perform shift operations such as left shift, right shift and circular shift operations which can then, in theory be used to construct arithmetic circuits. \n",
    "\n",
    "In this tutorial, we'll learn what it means to perform a shift operation, how a shift register works and how you can implement your own shift register using quantum gates!\n",
    "\n",
    "### Pre-requisites\n",
    "These are a few pre-requisites that you might require to follow along better with this tutorial:\n",
    "- Basics of python\n",
    "- Basics of programming with Qiskit\n",
    "- Basics of quantum gates \n",
    "\n",
    "Resources for all of the above mentioned pre-requisites can be found [here!](https://github.com/QForestCommunity/launchpad/blob/master/README.md)\n",
    "\n",
    "However, all the quantum gates involved will be covered in brief in this tutorial. \n",
    "\n",
    "### Dependencies\n",
    "Dependencies that you'll require to execute the code in this tutorial:\n",
    "- qiskit\n",
    "\n",
    "You can install qiskit by following the [this](https://www.youtube.com/watch?v=M4EkW4VwhcI&list=PLOFEBzvs-Vvp2xg9-POLJhQwtVktlYGbY&index=3&t=0s) tutorial!\n",
    "\n",
    "### Contributors\n",
    "[Madhav Jivrajani](https://github.com/MadhavJivrajani)\n",
    "\n",
    "#### Qiskit Package Versions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'qiskit-terra': '0.14.1',\n",
       " 'qiskit-aer': '0.5.1',\n",
       " 'qiskit-ignis': '0.3.0',\n",
       " 'qiskit-ibmq-provider': '0.7.1',\n",
       " 'qiskit-aqua': None,\n",
       " 'qiskit': '0.19.2'}"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import qiskit\n",
    "qiskit.__qiskit_version__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## _Introduction and background_\n",
    "\n",
    "A typical shift register typically shifts data in a particular direction, i.e. either towards the left or towards the right. \n",
    "\n",
    "For example, if x is a sequnce of $n$ bits, $a_1 a_2 a_3 ... a_n$ and $f(x)$ is a function that performs a single left shift operation on the sequence $x$ then,\n",
    "\n",
    "$$f(x) = a_2 a_3 ... a_n0$$\n",
    "\n",
    "More formally, a shift register is a device that shifts data bits to the nearest data bit in a particular direction. The data bit that is shifted 'out' is lost in a typical shift register as shown in the above equation. \n",
    "\n",
    "Shift registers can be _circular_ in nature as well. This means that the data bit that is shifted out is not lost, but rather re-enters the register from the other end and data bits are cycled in a particular direction. \n",
    "\n",
    "For example, if x is a sequnce of $n$ bits, $a_1 a_2 a_3 ... a_n$ and $g(x)$ is a function that performs a single circular left shift operation on the sequence $x$ then,\n",
    "\n",
    "$$g(x) = a_2 a_3 ... a_na_1$$\n",
    "\n",
    "The symbols for a left shift and a circular left shift are `<<` and `<<<` respectively. \n",
    "\n",
    "### How can quantum gates be used to implement a shift register?\n",
    "\n",
    "In classical shift registers, the data bit that is shifted out is virtually lost. This property can be attributed to the irreverability of classical circuits. Since we know that quantum gates are unitary in nature, we cannot convert a classical circuit into a quantum circuit. \n",
    "\n",
    "Intuitively, we can look at a shift operation as _copying_ the value of the data bit from the current position to the next data bit in the direction of the shift. This works perfectly fine in the classical case. But, here's the cool thing:\n",
    "\n",
    "![meme](img/quantum_shift_register/qsr_meme.png)\n",
    "\n",
    "  \n",
    "  \n",
    "    \n",
    "In quantum computation, we can't really copy a quantum state and since the data of the shift register is encoded in the qubits, which are in a quantum state, it cannot be copied. This is because of a theorem called the [no cloning theorem](https://www.youtube.com/watch?v=owPC60Ue0BE). Because of this, we need additional qubits to perform a shift operations, and we call these additional qubits _ancillary_ qubits. Now that we have additional qubits to help us, instead of copying data from one qubit to the next, what we can do is sequentially keep _swapping_ values of adjacent qubits starting from the last ancillary qubit to the first data qubit. For example, let's take the register to hold the value $x = 1011$ initially. As mentioned above, if we were to apply a left shift operation, $f(x)$ should result in $0110$. Let's try and visualize what this looks like along with the swap operations that we just discussed. Notice that the swap operations happen sequentially and are not all at the same logic level.  \n",
    "\n",
    "![left_shift](img/quantum_shift_register/left_shift.png)\n",
    "\n",
    "If the initial values of the ancillary qubits were $b_1b_2...b_n$ and initial values of the data qubits were $a_1a_2...a_n$, if the operation performed is a simple left shift operation, then after one shift operation ($2n - 1$ swaps), the values of the ancillary qubits would be $a_nb_2b_3...b_n$ and the data qubits become $a_2a_3...b_1$. \n",
    "\n",
    "These \"swaps\" can be easily done by the swap quantum gate. The swap gate looks like so ([source](https://en.wikipedia.org/wiki/File:Swap_gate.svg)):\n",
    "\n",
    "![swap_gate](img/quantum_shift_register/swap_gate.png)\n",
    "\n",
    "Let's look at a small code snippet in qiskit demonstrating the swap gate!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "from qiskit import QuantumCircuit, BasicAer, execute\n",
    "from qiskit.visualization import plot_histogram"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 418.992x204.68 with 1 Axes>"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "qcSwap = QuantumCircuit(2, 2) #create a quantum circuit with 2 quantum bits and 2 classical bits.\n",
    "\n",
    "qcSwap.x(0) #apply a pauli X gate to the first qubit to better demonstrate the swap.\n",
    "qcSwap.swap(0, 1) #apply a swap gate on the first and second qubits. \n",
    "\n",
    "qcSwap.measure([0, 1], [0, 1]) #measure the qubits to see what their states end up being\n",
    "\n",
    "qcSwap.draw(output = \"mpl\") #draw the circuit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'10': 1}\n"
     ]
    }
   ],
   "source": [
    "backend = BasicAer.get_backend(\"statevector_simulator\")\n",
    "state = execute(qcSwap, backend, shots=1024).result().get_counts()\n",
    "\n",
    "#the initial state should've been '01' before the swap,\n",
    "#go ahead and comment the swap gate out and run the code!\n",
    "\n",
    "#the state is '01' before the swap because of qiskit's little endian encoding.\n",
    "print(state)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Let's create a quantum circuit for the above discussed swap approach!\n",
    "\n",
    "Now that we know what a swap gate does, let's try a create a quantum circuit for the shift via swap approach that we discussed above."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 1081.19x565.88 with 1 Axes>"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n = 4 #number of data qubits.\n",
    "ancilla = n #number of ancillary qubits is the same as number of qubits in this example.\n",
    "\n",
    "#number of classical registers is equal to the number of data qubits, since we want the values of only those.\n",
    "qcShift = QuantumCircuit(n + ancilla, n)\n",
    "\n",
    "seed = \"1011\" #this is the initial value of our data qubits.\n",
    "seed = list(map(int, list(seed)))[::-1] #reverse the list to follow qiskit's encoding scheme.\n",
    "\n",
    "#to encode the seed, when we encounter a 1, we apply a pauli x gate. \n",
    "for bit in range(len(seed)):\n",
    "    if seed[bit] == 1:\n",
    "        qcShift.x(bit)\n",
    "qcShift.barrier(range(n + ancilla)) #add a barrier to mark the end of the encoding phase.\n",
    "\n",
    "#to apply the swap gates\n",
    "for qubit in range(1, n + ancilla)[::-1]:\n",
    "    qcShift.swap(qubit, qubit - 1)\n",
    "qcShift.barrier(range(n + ancilla)) #add a barrier to mark the end of the swapping phase.\n",
    "\n",
    "#measure the values of the data qubits.\n",
    "qcShift.measure(range(n), range(n))\n",
    "qcShift.barrier(range(n + ancilla)) #add a barrier to mark the end of the measuring phase.\n",
    "\n",
    "qcShift.draw(output = \"mpl\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### What about a circular shift operation?\n",
    "\n",
    "The above circuit works well for a left shift operation, but what if we want to perform shifts circularly? \n",
    "\n",
    "Notice in the above circuit that the value that is shifted out is shifted out of $a_1$. Now, to achieve a circular or a cyclic shift operation as described by $g(x)$, this shifted out bit needs to be fed back into the register at the opposite end. Or in other words, this shifted out bit needs to come into $a_n$. But since we are using ancillary qubits and swaps, we need to put this shifted out value into $b_1$ whose value is then fed into $a_n$ via a swap. \n",
    "\n",
    "![circular_left_shift](img/quantum_shift_register/circular_left_shift.png)\n",
    "\n",
    "\n",
    "To sort of generalize this idea of left shift, we can add a \"flag\" qubit or a \"control\" qubit such that if its value is 1, it will perform the swap as mentioned above, if not it will not perform the final swap and the operation will equivaluent to $f(x)$. Therefore, we need something like a _controlled_ swap gate.\n",
    "\n",
    "A controlled swap gate exists and is called the Fredkin gate and interestingly is one of the universal quantum gates! A fredkin gate looks something like this:\n",
    "\n",
    "![fredkin](img/quantum_shift_register/fredkin.png)\n",
    "\n",
    "This essentially means that if the control qubit is 1, only then the swap operations will take place. \n",
    "\n",
    "Usually, gates such as the Fredkin gate, Toffoli gate, etc are considered to be large gates and are implemented by breaking them down in terms of simpler gates. In qiskit it's easier to implement the Fredkin gate in terms of 2 controlled not gates and one doubly controlled not gate or the toffoli gate as explained [here](https://quantumcomputing.stackexchange.com/questions/9342/how-to-implement-a-fredkin-gate-using-toffoli-and-cnots). \n",
    "\n",
    "\n",
    "Instead of writing code for applying the swaps and the controlled swaps, why not turn the entire swap operation buisness into one big   \n",
    "`quantum shift gate`. This can easily be done in Qiskit by using the `to_gate()` method. A demo for the same can be found [here!](https://www.youtube.com/watch?v=krhPpzkT_z4)\n",
    "\n",
    "### Having, discussed that, let's create out circuit for quantum shift registers!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 1502.59x626.08 with 1 Axes>"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def create_shift_gate(n:int, circular:bool = False):\n",
    "    \"\"\"Creates a gate out of a shift circuit.\n",
    "    \n",
    "    Args:\n",
    "        n        : number of data qubits.\n",
    "        seed     : initial state of the data qubits.\n",
    "        circular : flag indicating whether the shift register is circular in nature or not.\n",
    "    \"\"\"\n",
    "    \n",
    "    if circular:\n",
    "        name = \"Circular Left Shift\"\n",
    "    else:\n",
    "        name = \"Left Shift\"\n",
    "        \n",
    "    ancilla = n\n",
    "    \n",
    "    #n data qubits and the same number of ancillary qubits and one extra qubit to act as the control\n",
    "    #bit for deciding if the operation should be a left shift or a circular left shift.\n",
    "    shiftGate = QuantumCircuit(n + ancilla + 1, name=name)\n",
    "        \n",
    "    for qubit in range(1, n + ancilla)[::-1]:\n",
    "        shiftGate.swap(qubit, qubit - 1)\n",
    "    \n",
    "    #implement the controlled swap.\n",
    "    shiftGate.cx(0, n)\n",
    "    shiftGate.toffoli(n + ancilla, n, 0)\n",
    "    shiftGate.cx(0, n)\n",
    "    \n",
    "    return shiftGate.to_gate()\n",
    "\n",
    "n = 4\n",
    "seed = '1011'\n",
    "ancilla = n\n",
    "\n",
    "#n data qubits and the same number of ancillary qubits and one extra qubit to act as the control\n",
    "#bit for deciding if the operation should be a left shift or a circular left shift.\n",
    "shiftCirc = QuantumCircuit(n + ancilla + 1, n)\n",
    "\n",
    "seed = list(map(int, list(seed)))[::-1]\n",
    "circular = True\n",
    "\n",
    "#encode the circuit\n",
    "for bit in range(len(seed)):\n",
    "    if seed[bit] == 1:\n",
    "        shiftCirc.x(bit)\n",
    "if circular:\n",
    "    shiftCirc.x(n + ancilla) #encode the control qubit.\n",
    "shiftCirc.barrier(range(n + ancilla + 1))\n",
    "\n",
    "shiftGate = create_shift_gate(n, circular)\n",
    "\n",
    "#perform 2 shift operations.\n",
    "shiftCirc.append(shiftGate, range(n + ancilla + 1))\n",
    "shiftCirc.append(shiftGate, range(n + ancilla + 1))\n",
    "shiftCirc.barrier(range(n + ancilla + 1))\n",
    "\n",
    "#get the state of the data qubits.\n",
    "shiftCirc.measure(range(n), range(n))\n",
    "shiftCirc.barrier(range(n + ancilla))\n",
    "\n",
    "#draw the circuit.\n",
    "shiftCirc.draw(output=\"mpl\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 504x360 with 1 Axes>"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#get the state of the shift register\n",
    "backend = BasicAer.get_backend(\"statevector_simulator\")\n",
    "register_state = execute(shiftCirc, backend, shots=1024).result().get_counts()\n",
    "\n",
    "plot_histogram(register_state)\n",
    "\n",
    "#as it can be seen, the state of the register is '1110' which is what\n",
    "#you would get by performing two left shift operations circularly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 780.192x565.88 with 1 Axes>"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#to see what the shift gate is acutally made up of. \n",
    "seeShiftGate = QuantumCircuit(n + ancilla + 1)\n",
    "seeShiftGate.append(shiftGate, range(n + ancilla + 1))\n",
    "\n",
    "seeShiftGate.decompose().draw(output = \"mpl\")\n",
    "#q8 is the control qubit. q0-q3 are the data qubits and q4-q7 are the ancillary qubits."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You may have noticed in the above code that ancilla is always specified as a seperate variable when it's always equal to n. This is because, if you have some application in which you require the maximum number of shifts to be equal to a number that is less than n, then it can be achieved this way. \n",
    "\n",
    "A right shift operation can also be done in a similar manner by re-arranging the order in which the swaps is done. \n",
    "\n",
    "#### Congratulations! You made it to the end!\n",
    "\n",
    "### The entire source code for this tutorial can be found [here](https://github.com/MadhavJivrajani/pyQSR)!\n",
    "\n",
    "### References\n",
    "\n",
    "[1] Jae-weon Lee and Eok Kyun Lee and Jaewan Kim and Soonchil Lee, Quantum Shift Register, 2001.\n",
    "    https://arxiv.org/abs/quant-ph/0112107"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
